TextWidth

TextWidth
Header:	QuickdrawText.h		Carbon status:	Supported

Returns the length, in pixels, of the specified text.

SInt16 TextWidth (
    const void *textBuf, 
    SInt16 firstByte, 
    SInt16 byteCount
);

Parameter descriptions

textBuf: A pointer to a buffer that contains the text to be measured.
firstByte: An offset from textBuf to the first byte of the text to be measured.
byteCount: The number of bytes of text to be measured.

function result: The length, in pixels, of the specified text.

DISCUSSION

You can use TextWidth to measure the screen pixel width of any text segment that has uniform character attributes. You can use it to measure the style runs in a line of text, whether you intend to draw the line using DrawText or DrawJustified. The TextWidth function takes into account the character attributes set in the graphics port. If you change any of these attributes after determining the text width but before actually drawing the text, the predetermined width may not be correct. For a space character, TextWidth also includes the effect of SpaceExtra. For a nonspace character, TextWidth includes the effect of CharExtra.

Because this function measures text in the font, style, and size of the current graphics port, you need to call it once for each individual style run in any line of text that contains multiple style runs.

The TextWidth function works with text in all script systems because the script management system modifies the function if necessary to give the proper results.

To draw justified lines of text that include multiple style runs, you calculate the amount of extra pixels, or slop, that remains to be distributed throughout the line. This process entails measuring the screen pixel width of each style run on the line: you can use TextWidth for this purpose.

For 1-byte complex script systems, TextWidth calculates the widths of any ligatures, reversals, and compound characters that need to be drawn.

Note that byteCount is the number of bytes to be measured, not the number of characters. Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.